package tech.waterism.service.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

/**
 * CORS 跨域配置
 * 
 * <p>解决前后端分离项目中的跨域资源共享问题。
 * 
 * <p><strong>配置说明：</strong></p>
 * <ul>
 *   <li>允许所有来源（生产环境建议限制特定域名）</li>
 *   <li>允许所有HTTP方法（GET, POST, PUT, DELETE等）</li>
 *   <li>允许所有请求头</li>
 *   <li>允许携带凭证（Cookie、Authorization等）</li>
 *   <li>预检请求缓存时间：3600秒（1小时）</li>
 * </ul>
 * 
 * <p><strong>生产环境安全建议：</strong></p>
 * <pre>
 * // 仅允许特定域名
 * config.setAllowedOrigins(Arrays.asList(
 *     "http://your-domain.com",
 *     "https://your-domain.com"
 * ));
 * 
 * // 或使用通配符（谨慎使用）
 * config.setAllowedOriginPatterns(Arrays.asList("https://*.your-domain.com"));
 * </pre>
 *
 * @author 高宇
 * @version 1.0
 * @since 2025-01-25
 */
@Configuration
public class CorsConfig {

    /**
     * 配置 CORS 过滤器
     * 
     * @return CorsFilter 实例
     */
    @Bean
    public CorsFilter corsFilter() {
        // 创建 CORS 配置对象
        CorsConfiguration config = new CorsConfiguration();
        
        // ==================== 允许的来源 ====================
        // 方式1: 允许所有来源（开发环境）
        config.addAllowedOriginPattern("*");
        
        // 方式2: 允许特定来源（生产环境推荐）
        // config.addAllowedOrigin("http://59.46.146.11:8083");
        // config.addAllowedOrigin("http://localhost:8083");
        // config.addAllowedOrigin("http://localhost:3000");
        
        // 方式3: 允许通配符模式（推荐用于生产环境）
        // config.addAllowedOriginPattern("http://*.your-domain.com");
        // config.addAllowedOriginPattern("https://*.your-domain.com");
        
        // ==================== 允许的HTTP方法 ====================
        config.addAllowedMethod("*");  // 允许所有方法
        // 或者明确指定：
        // config.addAllowedMethod("GET");
        // config.addAllowedMethod("POST");
        // config.addAllowedMethod("PUT");
        // config.addAllowedMethod("DELETE");
        // config.addAllowedMethod("OPTIONS");
        
        // ==================== 允许的请求头 ====================
        config.addAllowedHeader("*");  // 允许所有请求头
        // 或者明确指定：
        // config.addAllowedHeader("Content-Type");
        // config.addAllowedHeader("Authorization");
        // config.addAllowedHeader("X-Requested-With");
        
        // ==================== 暴露的响应头 ====================
        config.addExposedHeader("*");  // 允许客户端访问所有响应头
        // 或者明确指定：
        // config.addExposedHeader("Content-Disposition");
        // config.addExposedHeader("X-Total-Count");
        
        // ==================== 是否允许携带凭证 ====================
        config.setAllowCredentials(true);  // 允许携带Cookie、Authorization等凭证
        
        // ==================== 预检请求缓存时间 ====================
        config.setMaxAge(3600L);  // 预检请求结果缓存1小时（3600秒）
        
        // 创建 CORS 配置源
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        
        // 对所有路径应用 CORS 配置
        source.registerCorsConfiguration("/**", config);
        
        // 返回 CorsFilter
        return new CorsFilter(source);
    }
}

